Using the DinkeyChange API with MATLAB

If you are not already familiar with calling shared libraries from MATLAB code, it is strongly recommended that you read the MATLAB documentation on this topic. Depending on your version of MATLAB, you may need to install a C compiler and configure MATLAB to use it with the command mex -setup. Again, refer to the MATLAB documentation for further information.

See Remote Parameter Changing > DinkeyChange > DinkeyChange.dll in the user manual for information on using the DinkeyChange API. Use the help command to see overviews of how each M-file interface to the DinkeyChange API is used in MATLAB. Most of the DinkeyChange M-files are simple MATLAB wrappers for the shared library functions. dcgetinfo.m however is quite different to the DCGetInfo() function described in the user manual:

[retCode, dongleArray] = dcgetinfo(libName, typeMask, modelMask, prodcodeMask)

The inputs typeMask, modelMask and prodcodeMask are used in the same way as the inputs of DCGetInfo(), as dcsample.m illustrates. The outputs however are grouped together as dongleArray, a 1-by-N vector of MATLAB structures. Each structure represents a dongle found by dcgetinfo's search, and each structure has the following fields:

Field	Data Type	Description
type	int32	The dongle's type as a numeric value. Possible values: 1 for Dinkey Pro dongles 2 for Dinkey FD dongles
type_as_string	char	The dongle's type as a string. Possible values: "Pro" "FD"
model	int32	The dongle's model as a numeric value. Possible values: 1 for Lite dongles 2 for Plus dongles 4 for Net dongles (5 users) 7 for Net dongles (unlimited users)
model_as_string	char	The dongle's model as a string. Possible values: "Lite" "Plus" "Net (5 users)" "Net (unlimited users)"
product_code	char	The dongle's product code
dongle_number	uint32	The dongle's serial number (dongle number)
update_number	int32	The dongle's update number

MATLAB Example Files

dcgetinfo.m - an M-file that provides a MATLAB interface to the DCGetInfo() API function.
dcgetdiagnosticinfo.m - a MATLAB interface to the DCGetDiagnosticInfo() API function.
dcdoupdatecodestring.m - a MATLAB interface to the DCDoUpdateCodeString() API function.
dcdoupdatecodefromfile.m - a MATLAB interface to the DCDoUpdateCodeFromFile() API function.
dcrestoredinkeyfdlite.m - a MATLAB interface to the DCRestoreDinkeyFDLite() API function.
dcgetmachineid.m - a MATLAB interface to the DCGetMachineID() API function.
dcdownloadtempsoftwarekey.m - a MATLAB interface to the DCDownloadTempSoftwareKey() API function.
dcdownloaddemosoftwarekey.m - a MATLAB interface to the DCDownloadDemoSoftwareKey() API function.
dcsample.m - examples of using these M-files.
dinkeychangewin32proto.p - a prototype P-file that defines the signatures of the API functions for 32-bit MATLAB on Windows.
dinkeychange32proto.p - a prototype P-file that defines the signatures of the API functions for 32-bit MATLAB on all other supported platforms.
dinkeychange64proto.p - a prototype P-file that defines the signatures of the API functions for 64-bit MATLAB on all supported platforms.
DinkeyChange64_thunk_pcwin64.dll - a compatibility layer required by 64-bit MATLAB to use DinkeyChange64.dll.

The appropriate prototype P-file and any M-files that you call should be included, without modification, in your own project. If you are using 64-bit MATLAB on Windows, you should also include DinkeyChange64_thunk_pcwin64.dll. If you rename DinkeyChange64.dll, you must change the DinkeyChange64 part of the thunking DLL's filename accordingly.

Our M-files and P-files are compatible with MATLAB on macOS and Linux. However, we do not currently provide the thunk files required by 64-bit MATLAB on these platforms. If you want to use the DinkeyChange API on 64-bit macOS and/or 64-bit Linux, please contact us with full details of the platform(s) and MATLAB versions that you want to use, and we can provide compatible thunk files or instruct you on how to produce these files yourself.

Supported Versions

The MATLAB sample code provided with the Dinkey Pro/FD SDK was written and tested using MATLAB R2013a. All newer versions should be backwards compatible. The sample code may also work with older versions, but no guarantees can be made, and support for older versions is likely to be very limited.

Try It Yourself

dcsample.m gives a simple example of calling each of the API functions. To run dcsample.m you will need a copy of the appropriate shared library for your platform (DinkeyChange.dll for 32-bit Windows, DinkeyChange64.so for 64-bit Linux etc.). Place the library in the same folder as the example files and change MATLAB's current directory to this folder. Browse the examples in dcsample.m to see how different features can be used.

Uncomment the function calls at the top of dcsample.m to enable the examples of different features, then enter dcsample in the Command Window to run the examples.

dcsample.m also demonstrates loading and unloading the appropriate shared library for your platform.

Parts of the sample code marked with !!!! must be customised with your own functions or values for some features to work correctly. Not all features are supported by all dongle models. See the user manual for more information.